home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.1 / Docs / Instructions < prev    next >
Encoding:
Text File  |  1999-10-27  |  16.9 KB  |  419 lines
  1.  
  2. 3.1 Amiga Developer Update Disks
  3. (c) Copyright 1985-1999 Amiga, Inc.  All Rights Reserved
  4.  
  5. Some additional copyrights may be noted in individual files and docs.
  6.  
  7. These materials are not freely redistributable.  However some
  8. individual archives on these disks may contain their own licensing
  9. or redistribution information.
  10.  
  11.  
  12.                Instructions
  13.                            ============
  14.  
  15. Welcome to the 3.1 Amiga Developer Update disk set.
  16.  
  17. These disks contain includes files, libs, autodocs, examples, tutorials,
  18. and debugging tools for developing Amiga software for versions V38 (2.1),
  19. V39 (3.0) and V40 (3.1) of the Amiga OS.  These materials can also be used
  20. to develop code for earlier version of the Amiga OS, since the materials
  21. include all earlier OS structures and functions.
  22.  
  23. There is a lot of material here.  The "Contents" file on this disk
  24. contains a full list of everything included on this disk set.
  25.  
  26. Please note that very few of the files and directories on these disks
  27. have icons.  To see all of the files on the disks, use the Show All
  28. feature of 2.0 and higher Workbench, or use the Amiga shell.
  29.  
  30. This document will give you an overview of what's provided on the disks,
  31. and some help with decompressing the archives and using the materials.
  32.  
  33.  
  34. What's Here
  35. ===========
  36.  
  37. Docs disk highlights
  38. --------------------
  39.  
  40. 1. Autodocs
  41. The Amiga autodocs are the function summaries for the V40 Amiga OS.
  42. In general, all functions, libraries, and devices from previous Amiga
  43. OS's are also covered.  Please note that narrator.device and the
  44. translator.library are not currently part of the Amiga OS, and are
  45. not licensable, so please don't write software which requires these.
  46. Also, all functions newer than 1.2 are generally marked with the
  47. first version number in which they appeared.
  48.  
  49. 2. Tutorials
  50. These are tutorial documents about new features of V38 and V39.
  51. AA graphics, locale, bullet, datatypes, and other features are discussed.
  52. But you won't find AA register descriptions.  Use the OS.
  53. New V40 (3.1) libraries and devices are not covered, but there are
  54. autodocs for these (lowlevel.library, nonvolatile.library, cd.device).
  55. Licensed AmigaCD developers receive additional docs and examples
  56. for these new V40 subsystems. See additional notes about 3.1 at the
  57. end of this document.
  58.  
  59. 3. Contents listing
  60. A full listing of the contents of the 3.1 Amiga Developer Update disks.
  61. Use this to find what you are looking for.
  62.  
  63. 4. LHEX
  64. If you don't have LhA by Stefan Boberg, the LHEX tool provided on
  65. the Examples2 disk can also be used for decompressing the archives
  66. on this disk.  The flags for LHEX are slightly different from the flags
  67. for LhA, and LHEX has fewer options and only supports decompression.
  68. For information on decompressing the archives on these disks, see
  69. "Decompressing the Archives" later in these Instructions.
  70.  
  71.  
  72. Includes&Libs disk highlights
  73. -----------------------------
  74.  
  75. 1. Amiga include files
  76. The include_h.lha archive contains the C include files.  The include_i.lha
  77. archive contains the assembler include files.  I believe it is no longer
  78. possible to fit all of the include files on a normal density diskette,
  79. even if formatted with fast filesystem.  If you have a hard disk,
  80. decompress both archives to the same directory.  If you have a floppy
  81. based system, you'll probably want to decompress them each to a separate
  82. disk.
  83.  
  84. 2. Linker_libs and FD's
  85. Here are amiga.lib, debug.lib, etc. and the FD (function definition)
  86. files for V40.  The LVO tool (SWToolkit3 disk) can be used with
  87. the FD files to list LVO offsets and other information.
  88.  
  89. 3. Using_Includes
  90. A readme about updating your development environment, and about
  91. compiling new and old code with the new 3.1 Includes.  Includes
  92. hints for beginners on what include files to include.
  93.  
  94. 4. StructOffsets.lha
  95. Contains the Structure.Offsets file for 3.1 which lists the sizes,
  96. member sizes, and member offsets of 3.1 Amiga structures.
  97.  
  98. 5. DevTools archive
  99. Contains tools for development like bumprev and autodoc, plus old
  100. code tools like ALink and Atom.
  101.  
  102. 6. Debug_Examples archive
  103. Contains example code using kprintf, and C include files with simple
  104. debugging macros you can turn on and off (much neater than having
  105. a lot of #ifdefs in your source code).
  106.  
  107. 7. startups37 archive
  108. The 2.0 Amiga startup code source and objects - useful for assembler
  109. code, and for Amiga-specific non-base-releative C code that doesn't require
  110. your compiler's startup code but needs command line argument parsing
  111. and/or handling of Workbench startup.
  112.  
  113. 8. SetPatch37.lha and SetPatch40.lha
  114. These archives contain updates to SetPatch to fix OS bugs and
  115. in some cases enhance compatibility.  SetPatch37.lha contains
  116. SetPatch 37.39 for Amigas running V37 (2.04) Kickstart.
  117. SetPatch40.lha contains SetPatch 40.14 for Amigas running V38 (2.1)
  118. through V40 (3.1).  Each archive includes a click-on installation
  119. script and readme.
  120.  
  121. 9. runtime_libs.lha
  122. This archive contains iffparse.library 37.1 and realtime.library 34.5
  123. for use on Amiga systems that don't already have these libraries.
  124. Free electronic licenses are included for distribution of these versions.
  125. V37 and higher systems already have iffparse.library, but versions 38 and
  126. upwards of this library require at least V37 OS.  V40 Workbench includes
  127. a realtime.library that requires at least V37 OS.  The earlier versions
  128. supplied here work under 1.3, and should even work under 1.2 (not tested).
  129. IFFParse.library is required by the NewIFF39 code modules and examples.
  130. Realtime.library is a new library that provides a way for tasks to
  131. share high resolution timing and also to synchronize with each other.
  132. See the autodoc realtime.doc in the V40 autodocs for more information.
  133.  
  134.  
  135. Examples1 Disk highlights
  136. -------------------------
  137.  
  138. Code examples for many new V38 and V39 features including locale,
  139. intuition, asl, colorwheel, graphics, gadtools, and asynchio packets
  140. example.  The locale examples include special code you can link with
  141. to load your own locale catalogs under V37, and a tool to help you
  142. automate some of the work in localizing old code.  Note - the CatComp
  143. tool for creating catalogs and its doc are on the SWToolKit3 disk.
  144. The Locale tutorials are on the Docs disk in the tutorials archive.
  145. Of special note - PCMCIA.lha contains several tutorial articles
  146. about PCMCIA and some useful tools and examples, plus information
  147. on ordering the PCMCIA specs.
  148.  
  149.  
  150. Examples2 Disk highlights
  151. -------------------------
  152.  
  153. Big code archives for NewIFF39 (1.3-compatible yet AA-capable IFF code
  154. modules and examples), DataTypes examples, new picture datatypes,
  155. and also the AmigaGuide archive featuring free electronic license for
  156. AmigaGuide.  Notes - the Datatypes tutorial is on the Docs disk in the
  157. tutorials archive.  The NewIFF archive includes a ScreenSave program
  158. and the ILBM slide show program Display.
  159.  
  160.  
  161. SWToolkit3 highlights
  162. ---------------------
  163.  
  164. This disk contains all of the Amiga debugging tools, other handy tools,
  165. and the Amiga "report" program for generating bug reports and enhancement
  166. requests in the correct format.  Here you'll find Mungwall, Enforcer,
  167. Wedge, new Wack (archived), IO_Torture, Sushi (captures debug output
  168. on one machine), LVO, and other important debugging tools.  A new
  169. setcamg tool is here also - useful for zapping the display mode
  170. of ILBMs.  Here you will also find the CatComp tool for making
  171. locale catalogs.
  172.  
  173. The docs for all of the Toolkit tools are archived on this disk.
  174. Tools with large doc files will have their own .doc files, and the rest
  175. are documented in OtherTools.doc.  Some tools are documented in the
  176. .doc files of the main tool with which they are distributed.  See
  177. the beginning of OtherTools.doc for a listing tells you where to find
  178. the docs for such tools.
  179.  
  180. Note - some older tools such as ShowLocks and SysPM have been left in
  181. the toolkit even though they have not been updated. 
  182.  
  183. Of special note - 
  184.  
  185.     - New Enforcer for V37 and up (old Enforcer now called Enforcer1.3)
  186.     - SegTracker. Start this up right after SetPatch!  It allows
  187.           many other tools to report Hunk and Offset information for
  188.           code hits and crashes.  See Enforcer.doc
  189.         - FindHit.  If you have compiled or assembled your code with
  190.           LINE debugging, FindHit can tell you a source code line
  191.           from hunk and offset information.  See Enforcer.doc
  192.         - Sushi.  Allows use of all serial debugging tools and kprintf
  193.           on a single system, without writing to your actual
  194.           serial hardware, modems, etc.  (note - you must use the
  195.           Enforcer RAWIO option for Sushi to pick up Enforcer output)
  196.     - Updated Mungwall and Munglist
  197.     - Wedge updated to use much less stack
  198.  
  199.  
  200.  
  201. Using The Amiga Developer Update Materials
  202. ==========================================
  203.  
  204. These materials are intended to be used in conjunction with the Amiga
  205. Rom Kernel programming manuals and examples for Release 2.0.
  206.  
  207. The 2.0 Rom Kernel manuals published by Addison-Wesley, plus
  208. The AmigaDOS Manual published by Bantam are the official programming
  209. manuals for the Amiga.  If you program for 2.0, it is easy to add V39/AA
  210. support by conditionally using the V39 32-bit-per-gun color loading
  211. functions to support the palette of 16,000,000 AA colors.
  212.  
  213. Fish Disks 741 and 742 include the 2.0 RKM Companion archives
  214. which contain the examples from the Amiga ROM Kernel Reference
  215. Manuals, 3rd edition.
  216.  
  217. Fish Disk 344 contains the 1.3 RKM Companion archives which
  218. contain the examples from the Amiga ROM Kernel Reference Manuals,
  219. 2nd edition.
  220.  
  221. The materials on these disks may be used to program for earlier versions
  222. of the Amiga OS.  For earlier OS's, don't use features, flags, structures,
  223. or functions which were added later.  Then add code to conditionally use
  224. any new functions which replace older methods of allocation or setting
  225. of flags.  Read the compatibility documents in this disk set and in
  226. the Release 2 ROM Kernel Manuals.
  227.  
  228.  
  229.         Published by Bantam Books (800-223-6834, NY & Canada 212-765-6500):
  230.  
  231.                 The AmigaDOS Manual 3rd Edition
  232.                         ISBN 0-553-35403-5
  233.  
  234.  
  235.         Published by Addison-Wesley (800-447-2226, 617-944-3700):
  236.  
  237.                 Amiga User Interface Style Guide
  238.                         ISBN 0-201-57757-7
  239.  
  240.                 Amiga Hardware Manual
  241.                         ISBN 0-201-56776-8
  242.  
  243.                 Amiga ROM Kernel Manual: Includes and Autodocs    
  244.                         ISBN 0-201-56773-3
  245.  
  246.                 Amiga ROM Kernel Manual: Devices (includes the IFF manual)
  247.                         ISBN 0-201-56775-X
  248.  
  249.                 Amiga ROM Kernel Manual: Libraries
  250.                         ISBN 0-201-56774-1
  251.  
  252.  
  253.  
  254. About 3.1 and CD32 (V40)
  255. ========================
  256. At the time of this writing, the 3.1 operating system has only been
  257. released in the Amiga CD32.  It is also available to registered developers
  258. in our closed electronic conferences for testing on other Amiga models.
  259.  
  260. If you wish to develop CD-ROM software for CD32, you must sign an
  261. AmigaCD license for your product.  Licensed AmigaCD developers have
  262. access to additional materials and tools for programming the CD32.
  263.  
  264. If you are developing an CD32 CD-ROM product, contact CATS - Licenses,
  265. 1200 Wilson Drive, West Chester, PA. 19380 (or FAX 215-429-0643)
  266. and request AmigaCD license forms.  Include your name and full surface
  267. mail address.
  268.  
  269.  
  270.  
  271. Becoming a Registered Developer
  272. ===============================
  273. Developers in our registered Amiga developer programs receive special
  274. mailings, discounts, and access to beta OS and other materials in our
  275. closed electronic conferences on BIX, CIX (UK), and ADSP (Europe).
  276.  
  277. In the US, two programs are currently available.  The Certified program
  278. costs approximately $100/year.  To join the Certified program, you must
  279. be developing a saleable product for the Amiga.  The Commercial program
  280. costs approximately $500/year, and includes personal phone support.
  281. The Commercial program is only open to developers with existing
  282. commercial computer products.  If you are developing a saleable
  283. product for the Amiga and would like a developer program application,
  284. this can be requested in the US from CATS-Applications at
  285. 1200 Wilson Drive, West Chester, PA. 19380 (or FAX 215-429-0643).
  286.  
  287.  
  288. Licensing Info
  289. ==============
  290.  
  291. These materials are not freely redistributable.  However some
  292. individual archives on these disks may contain their own licensing
  293. or redistribution information (including AmigaGuide.lha, SetPatch
  294. archives, and runtime_libs.lha).
  295.  
  296. An inexpensive distribution license for the 3.1 Includes and linker
  297. libs is available from Commodore.  Also available are licenses for
  298. earlier versions of the Includes.  In addition, Workbench licenses
  299. are available for Workbench 1.3, Workbench2.0, Workbench 2.1,
  300. and Workbench 3.0 (a Workbench 3.1 license should be available soon).
  301. Workbench licenses allow distribution of most of the files on a
  302. specific version of the Workbench disks, but do not include Arexx,
  303. CrossDOS, or outline fonts.  Includes and Workbench licenses do
  304. not allow any type of freely copyable distribution, and do require
  305. specific copyrights on your disk labels, and specific copyrights
  306. and disclaimers in your documentation.  The cost for an Includes
  307. license is currently $25 US/year.  The cost for a Workbench license
  308. is currently $100 US/year.  Renewals require documentation of
  309. compliance ith the license.
  310.  
  311. Licenses forms may be requested by name in the US by contacting
  312. CATS-Licenses at 1200 Wilson Drive, West Chester, PA. 19380
  313. (or FAX 215-429-0643).  Be sure to include your name, phone number,
  314. surface mail address, and the name(s) of the license(s) you require
  315. (i.e. Includes 3.1, Workbench 3.0, etc.).
  316.  
  317.  
  318. Decompressing the Archives
  319. ==========================
  320.  
  321. NOTE - in all of the examples below, the archive names are shown
  322. without paths.  Unless the archive is in your current directory,
  323. you must supply a full path to where the archive file is.
  324.  
  325. Example: LHEX x df0:DevTools/DevTools.lha
  326.  
  327. If you have enough RAM, dearchiving may go faster if you copy
  328. the archive to RAM: first, then dearchive it.
  329.  
  330. All of the usage examples also assume that your dearchiving tool
  331. is in one of your command paths.  Copy the dearchiving tool somewhere
  332. convenient where the system can find it (like to SYS:Tools, or to RAM:
  333. and then do PATH RAM: ADD)
  334.  
  335.  
  336. 1. Tools
  337.  
  338. If you have LhA by Stefan Boberg, you'll probably want to use that to
  339. decompress the archives.  LhA is fast and flexible.  If you don't
  340. have Lha, a tool called LHEX is provided on the Examples2 disk.
  341. LHEX is a tool from CATS for decompressing archives.  Its command line
  342. switches are fewer and different from LhA's.
  343.  
  344.  
  345. 2. General - Listing the archive
  346.  
  347. LhA Usage:   lha v archivename
  348. LHEX Usage:  lhex l archivename  (or just LHEX archivename)
  349.  
  350. Before decompressing any archive, you should list the archive to see if
  351. it will be placing everything in a directory or not.  This will determine
  352. where the destination for decompression should be.
  353.  
  354. For example, when we list the contents of include_h.lha, we see that
  355. the files are stored as include/<directory>/<file>.h, as below:
  356.  
  357. [generic]            4542  35.8% Oct 15 10:24 include/clib/alib_protos.h
  358. [generic]            1136  19.1% Oct 15 10:25 include/clib/all_protos.h
  359. (etc.)
  360.  
  361. This shows that when we decompress this archive, it will create if
  362. necessary and dearchive into a directory called "include".
  363.  
  364. This means we should decompress the archive to parent directory of our
  365. current "include" directory.
  366.  
  367. The easy way to direct the destination for decompression is to CD to the
  368. directory where you wish the archive contents to go.  In the above case,
  369. this means we WOULD NOT CD into our existing "include" directory, but
  370. rather to its parent directory.  For example, if our include directory
  371. is Work:SC/include, we would CD to Work:SC, since the listing of
  372. the include archive shows it will want to find (or create) a directory
  373. called "include".
  374.  
  375. Alternately, if you have enough RAM, the safest way to decompress archives
  376. is to make a temporary directory in RAM: (called "tmp" or whatever).
  377. CD into the temporary directory, and decompress the archive there.
  378. Then COPY ALL the files to the place where you want them.  If you are
  379. short on RAM, You could do the same by CD'ing to a temporary directory
  380. on your hard drive.
  381.  
  382.  
  383. 3. Decompressing an entire archive
  384.  
  385. LhA Usage:  LhA -rexa x archivename
  386. LHEX Usage: LHEX x archivename
  387.  
  388. The -rexa options for LhA tell it to preserve attribute bits, and create
  389. directories even if empty.  That's the same way LHEX decompresses.
  390. The above usage will decompress the archive to your current directory.
  391.  
  392. To decompress an entire archive to somewhere other than your current
  393. directory:
  394.  
  395. LhA Usage:  LhA -rexa x archivename destdir (must end with / or :)
  396. LHEX Usage: LHEX -w=destdir x archivename
  397.  
  398.  
  399. 4. Extracting individual files or directories from an archive
  400.  
  401. LhA Usage:  LhA -rexa x archivename filepattern
  402. LHEX Usage: LHEX x archivename filepattern
  403.  
  404. Note - I believe the filepattern may be case-sensitive.
  405.  
  406. First, list the archive to find the full path and name of the file
  407. or directory you wish to extract.  Then extract it.
  408.  
  409. Examples:
  410.  
  411. LhA:  LhA -rexa x autodocs.lha doc/amigaguide.doc
  412.       LhA -rexa x NewIFF39.lha newiff39/modules/*
  413.  
  414. LHEX: LHEX x autodocs.lha doc/amigaguide.doc
  415.       LHEX x NewIFF39.lha newiff39/modules/*
  416.  
  417.  
  418.  
  419.